{accessrmd} is currently in development. If you discover bugs or improvements, please review the code of conduct and contribute on GitHub.
{accessrmd} is a package written to help improve the accessibility of Rmarkdown documents. The standard Rmarkdown outputs have HTML structural issues that result in problems for people using screen readers. The purpose of {accessrmd} is to help developers in writing accessible Rmarkdown documents and in converting a back catalogue of documents in need of accessibility amendments.
{accessrmd} is currently limited to html_output only. It is not available on CRAN yet, but this is the aim once the first release has been published.
To install the development version:
devtools::install_github("datasciencecampus/accessrmd")
To attach the package:
library(accessrmd)
The HTML structure of standard rmarkdown outputs are not AA WCAG2.1 standard. AA is the standard required by all UK government digital services. In order to present HTML checks, I will be enlisting the help of the excellent, open-source WAVE accessibility tool. It doesn’t catch everything required for AA-compliance, but it’s a great way to get started with an accessibility audit, including helpful explanations for newcomers to WCAG 2.1 compliance.
The below image shows the output of a WAVE check on the standard Rmarkdown html output. As you can see, there are a number of errors and warnings. Click the image for more detail.
Click the image to view the full check on wave.webaim.org, opens in new window.
By executing a few functions from the {accessrmd} package, the html format issues can be easily remedied, without the developer needing to write any HTML. Please observe the output of an Rmarkdown which has been adjusted by {accessrmd} functions (again, you can click for an interactive check):
Click the image to view the full check on wave.webaim.org, opens in new window.
In this section, I will be working with a test Rmarkdown document. It contains a simple ggplot chart and a test image. Click to see the test Rmarkdown output.
access_head()Reads an Rmd file, converting the YAML header to a format that is screen-reader friendly.
access_img()Reads in an image and produces the HTML structure expected by web accessibility checkers such as WAVE. Also works as a wrapper around {ggplot2} charts.
check_alt_len()In development.
detect_html_lang()In development.
find_all_alts()In development.
find_all_imgs()Not exported. Find any markdown or HTML syntax images within read lines. Check any lines for images and return the line numbers and values.
handle_rmd_path()Not exported. Helper function.Checks rmd_path exists and that the file type is as expected.
sus_alt()Suspicious alt text - checks if an image’s alt text is equal to alt attribute placeholder values, including ‘nbsp’, ‘spacer’ and the src attribute value (filename).
A continuous deployment workflow has been employed in the development of {accessrmd}, using GitHub Actions.
This workflow has allowed efficient adaptation of the package modules while ensuring the integrity of the outputs and conditional behaviours.
CD workflows for this package include:
An automated test suite analagous to the checks run by CRAN on package submission.
This suite of checks is something that I tend to execute as part of my development practice. However, setting automated checks on push to the remote ensures that human error is mitigated. Collaborators or developers wishing to install the development version of {accessrmd} can be informed of the current state of the repository and assured of the package’s functionality.
As can be seen from the screenshot below, the package is tested for compatibility with three different operating systems, Windows, MacOS and 2 flavours of Ubuntu.
Clicking on an item in the check manifest allows you to view the detailed check schedule. If any checks failed, you can consult the log to help pinpoint the error.
Codecov test coverage
I utilise Test-Driven Development when writing software in order to mitigate against misuse cases.
@tired_actor ##duet with @brock1137 no please no ##funny ##Welcome2021 ##2021 ##newyear ##firstpost ##viral ##fyp ##foryou ##foryoupage ##comedy ##crying ##2020 ##RareAesthetic
♬ The Square Hole - Brock
All jokes to the side, ensuring that your functions are safe is vital. This helps mitigate against poor documentation and misinterpretation.
Code coverage gives an indication of the percentage of code lines that are exercised when the test battery is run. However, I would advise caution in assuming that a high coverage equates to quality software. It tends to be very easy to write a suite of tests that result in high coverage. This does not mean that all necessary exception handling has been considered and tested.
Thorough and well-considered test conditions are excellent tools in assuring quality software. It also means that you can turn your failures into future successes - every bug you encounter can be converted to a meaningful test.
Below, you can view the test coverage workflow on pushing to the remote.
Automated linting using the {lintr} package with GitHub actions is used to help ensure code adheres to the tidyverse style guide. Code readability is important in assisting collaboration. Data Science Campus guidance is to apply the tidyverse style guide.
Perhaps more important than the adopted style is to ensure that code is conscientiously commented. Your colleagues and future self will value the effort taken in explaining your code.